<HTML><HEAD><TITLE>session_start(++Login, ++Password, ++Options, -Session)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(dbi)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>session_start(++Login, ++Password, ++Options, -Session)</H1>
starts a new session for the DBMS
<DL>
<DT><EM>Login</EM></DT>
<DD>DBMS login: ID or ID@Host. (ID,Host: string or atom)
</DD>
<DT><EM>Password</EM></DT>
<DD>Password (string or atom)
</DD>
<DT><EM>Options</EM></DT>
<DD>Options (list or nil)
</DD>
<DT><EM>Session</EM></DT>
<DD>Session handle
</DD>
</DL>
<H2>Description</H2>
<P>
 Starts a new session with the DBMS. A new connection with the DBMS server is
 established, with the supplied DBMS user ID. Optionally, a host could be
 supplied, if the server is located on a remote machine. The host could be
 either the machine name, or an IP address. A session handle for this new
 connection is returned by the predicate.
</P><P>
 The session is closed automatically if the program backtracks or aborts back
 beyond this call. 
</P><P>
 Options is a (possibly empty) list of <TT>Option:Value</TT> pairs, specifying any
 options for this session. The following options are supported:
<DL>
<P>
<DT><STRONG><TT>dbname</TT></STRONG>
 <DD>Specifies the name of the database to use. Value can be a
     string or an atom. The same effect can also be achieved by issuing the
     SQL statement <TT>USE ...</TT> (where ... is the dbname).
<P>
<DT><STRONG><TT>storage</TT></STRONG>
 <DD>(MySQL specific) specifies the default storage model to use for
     the tables. Value can be either the string/atom <TT>transactional</TT>
     or <TT>non-transactional</TT>. For transactional tables, changes are
     local until they are committed. Uncommitted changes can be rollback.
     For non-transactional tables, changes are global. InnoDB (with autocommit
     turned off) is the storage  engine used for transactional, and MyISAM is
     the storage engine used for non-transactional. See the MySQL manual for
     details on storage engines and their effect on tables.
</DL>
<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>Login, Password or Options not of the correct type.
<DT><EM>(6) out of range </EM>
<DD>Invalid option specification in Options.
<DT><EM>(dbi_bad_field) </EM>
<DD>Problems with Option's argument.
<DT><EM>(dbi_error) </EM>
<DD>Problems connecting to DBMS server.
</DL>
<H2>Examples</H2>
<PRE>
     % connecting to a database server running on the local machine, as 
     % database user sqluser with password password
     session_start("sqluser", "password", [], S).

     % connecting to a database server running on machine my.sql.host,
     % as database user sqluser with password password, and selecting
     % to use the database mydb
     session_start(sqluser@my.sql.host, password, [dbame:"mydb"], S).
</PRE>
<H2>See Also</H2>
<A HREF="../../lib/dbi/session_close-1.html">session_close / 1</A>
</BODY></HTML>
